home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 April / Macworld (1999-04).dmg / Shareware World / Info / For Developers / MacCVS Pro 2.2.1 / Read Me < prev   
Text File  |  1999-01-20  |  14KB  |  341 lines
  1. ------------------------------------------------------------------------------
  2.                                 About MacCVS Pro
  3.                                 
  4.                             <http://www.maccvs.org/>
  5.  
  6. ------------------------------------------------------------------------------
  7.  
  8. Introduction
  9. ------------
  10.  
  11. * About MacCVS Pro
  12.  
  13. MacCVS Pro is a full-featured client for the CVS source code control
  14. system. It allows you to check in and out files to a network CVS
  15. repository as well as run other CVS commands such as CVS Log and CVS
  16. Status. In addition, MacCVS Pro is multi-threaded so you can execute
  17. multiple operations simultaneously.
  18.  
  19. MacCVS Pro was designed to be easy to use and very intuitive and does
  20. not assume the user is a software engineer or someone of similar
  21. background.
  22.  
  23. * About CVS
  24.  
  25. CVS, which stands for Concurrent Version System, is a system used for
  26. large- and small-scale software development projects, which tracks the
  27. revision history of all files in the project, allows multiple developers
  28. to work on the same source base, and allows for multiple versions of the
  29. project to be developed concurrently from the same source tree.
  30.  
  31. In CVS, the client and server usually run on different machines, and the
  32. client communicates with the server over a local area network, or the
  33. Internet. The CVS server software is available in source form, and
  34. should compile on most flavors of UNIX. 
  35.  
  36. For more information about CVS, see Cyclic's web site, at:
  37.  
  38.     <http://www.cyclic.com/cyclic-pages/overview.html>
  39.  
  40.  
  41. Installation & setup
  42. --------------------
  43.  
  44. These are intended to be introductory docs. For more detailed information,
  45. see the documentation online at <http://www.maccvs.org/>.
  46.  
  47. * Installation
  48.  
  49. MacCVS Pro simply needs to be copied onto your hard drive. All its settings
  50. are stored in the session files, so no additional files are required or
  51. created.
  52.  
  53. * Session settings
  54.  
  55. To start using MacCVS Pro on a source tree, you first need to make a
  56. session file. Run MacCVS Pro, and choose File:New to make a new
  57. session file. You will be prompted for a location to save the file;
  58. specify a name, and save the file. You will now see an empty window,
  59. which is a project view window.
  60.  
  61. Before checking out any source files, you have to specify the address
  62. of the CVS server, and some other details. Open the session settings from
  63. the Edit menu (also Command-;). There are four panels of settings here,
  64. accessible through the popup menu at the top of the dialog. The important
  65. settings are described below.
  66.  
  67. Panel 1 "Checkout and update options"
  68.     
  69.     At the top of this panel is a button used to set the root folder,
  70.     into which the source tree will go. Make a new folder in the 
  71.     Finder (say, in the same folder as the MacCVS session file you
  72.     just created), then switch back to MacCVS, click this "Set"
  73.     button and selection the folder you just made. This is where
  74.     the source tree will be created when you check out.
  75.     
  76.     The second grouping controls file merges. Use these options
  77.     to specify what happens on update when you have modified a file
  78.     locally, and someone else has also checked in changes. Most
  79.     people will want to use the "Auto Merge Text Files and Update
  80.     Binary Files".
  81.         
  82.     Finally, the last two fields, which are very important. Here
  83.     you specify the module, or directory you want to check out,
  84.     and the revision (tag) or date you wish to check out to
  85.     (if any). The default module will either be a module name
  86.     ("MacCVSPro") or a directory path ("src/maccvs/src/"). The
  87.     default revision may be empty, if you are checking out
  88.     to the tip, or it might be a branch tag ("MacCVS202_branch").
  89.  
  90. Panel 2 "Remote Host Information"
  91.     
  92.     This panel is used to specify the address of the CVS server,
  93.     your user name and password, and the root of the CVS tree
  94.     on the repository.
  95.     
  96.     The server hostname may be either a dotted name ("cvs.thisplace.com")
  97.     or IP addresss ("192.12.13.124"). User name is your user name
  98.     on the CVS server (which may be "anonymous" for a read-only server).
  99.     Password is your password on the server (some read-only servers
  100.     user "anonymous" here too). CVS Root specifies the root of the
  101.     source tree on the server, and will be given to you when you
  102.     get information about the CVS server. [See the section below about
  103.     interpreting UNIX-type CVS environment settings.]
  104.  
  105.     Next, there is a field you can use to adjust the amount of
  106.     time MacCVS waits before giving up on a connection. You might
  107.     want to increase this on a busy server, or slow connection.
  108.  
  109.     The lower panel here is used to control your authentication options
  110.     on the server. The normal method is 'Password', for which you just
  111.     need to enter a username and password in the fields. The other
  112.     authentication methods are not covered here, except to note that
  113.     the KClient option refers to Kerberos authentication, which requires
  114.     that you have Kerberos software installed. 
  115.     
  116.  
  117. Panel 3 "Encoding and file mappings"
  118.     
  119.     These settings determine what file types will be used for files
  120.     that MacCVS Pro creates. You can probably leave these alone
  121.     unless you are using a development environment other than
  122.     Metrowerks CodeWarrrior.
  123.     
  124. Panel 4 "Messages & Misc"
  125.     
  126.     The first two checkboxes control the verbosity of MacCVS Pro's
  127.     output messages. When checking out a new tree, you probably
  128.     want to just output messages for directories. When updating
  129.     an existing tree, outputting messages for every file is useful
  130.     so you can see what has changed.
  131.  
  132.     The next two checkboxes control the behaviour of the message
  133.     window. Check the "Automatically clear message window" box to
  134.     wipe out all message for each new operation. "Scroll to new messages"
  135.     is obvious, can can slow down things a bit.
  136.     
  137.     The New Folder properties refers to the look of folders in the Finder
  138.     that MacCVS Pro creates when you check out. For convenience, these
  139.     can be initialized to show in list mode.
  140.     
  141. * Interpreting UNIX-type CVS environment settings
  142.     
  143.     CVS settings are often specified for UNIX or Windows users,
  144.     and are given as something like:
  145.         
  146.         :pserver:anonymous@cvs1.mozilla.org:/cvsroot
  147.         
  148.     In MacCVS Pro-speak, that translates to:
  149.         1.    Use pserver authentication (Password option in settings).
  150.         2.    Username is "anonymous" (without the quotes). The password
  151.             will also be specified separately, so you will have to enter
  152.             that as well.
  153.         3.     The server address is cvs1.mozilla.org.
  154.         4.     The CVS root is /cvsroot (leading / is important!).
  155.     
  156.     The instructions then probably say something like "checkout the
  157.     module xyz", or, on the command line, "cvs checkout xyz". So
  158.     "xyz" is what you enter in the Default Module box.
  159.     
  160.     If checking out to a particular tag:
  161.         cvs checkout xyz -r bugfix_branch
  162.     then you enter "bugfix_branch" in the Default revision box.
  163.  
  164. * Checking out
  165.  
  166. Now you have the session settings set up, it's a good time to save the
  167. session file. All those settings are stored in the session file, as well
  168. as any other tags that you use for updating individual files.
  169.  
  170. So, to check out the entire source tree, go Action:Check out default module
  171. (Command-;). This gets the server to report which directories are in the
  172. default module (as specified in the session settings), and checks out those
  173. to your local disk. This can take some time, and eat up considerable amounts
  174. of disk space, depending on the size of the tree.
  175.  
  176. Congratulations! Now you have checked out the source tree, and can
  177. start to work on the code. You will notice that Codewarrior recognizes
  178. that files checked out in this way are read-only, and when you try
  179. to edit them for the first time, you have to make them writable. You
  180. can do this either from MacCVS Pro (Action:Modify read-only, Command-M)
  181. or in Codewarrior with the version control popup in the sourc window.
  182.  
  183. * Updating & merging
  184.  
  185. So you've edited a few files, and checked that they compile. Before you
  186. check in, you might want to update your local tree, to get any other changes
  187. that others have made since you checked out. You can either selection, and
  188. update specific directories in MacCVS Pro, or simply do a Check out defalt
  189. module again. If you want new changes merged into your modified files, 
  190. ensure that one of the 'Auto merge text files' options is turned on
  191. in the session settings. Binary files (e.g. GIF files, or resource files)
  192. cannot be merged, for obvious reasons, but MacCVS Pro updates them by
  193. copying your modified version to a ~0 file, and checking out the new
  194. version.
  195.  
  196. If both you and someone else have edited the same line in a source file,
  197. then you may get merge conflicts. These will show up as a message with a
  198. red warning icon. Merge conflicts must be resolved before you can check
  199. in. Double-click the conflict message to show the bad file, and double
  200. click the file to open it in CodeWarrior. A 'Make' will usually quickly
  201. show you where the conflicts are.
  202.  
  203. * Checking in
  204.  
  205. Once you have resolved any merge conflicts, and are sure that your
  206. changes build, you can check in. You can either simply show and
  207. select your modified files in the project view windows (the Finder-like
  208. views of your files), or you can use the Find Lurkers command to 
  209. list all new and modified files. In either case, select those files
  210. that you want to check in, and use the Action:Commit menu command.
  211. You will be asked for a checkin comment, and can select to use just
  212. one comment for all files, or separate ones for each. Type in
  213. a sensible command, and hit the Commit button. All being well,
  214. the CVS server should send back responses that the commit was
  215. successful, and the version number of the file will be updated.
  216.  
  217. * Gotchas
  218.  
  219. MacCVS is very careful about thread safetly and potential file
  220. corruption, and thus prevents some operations on source files which
  221. are open elsewhere. While updating or checking out, you must close
  222. any open files in CodeWarrior or other editors which are in the
  223. tree being updated, and you must close source files before committing
  224. them. If you try to do an operation on an open file that requires write
  225. access to the file's resource fork, you'll see a dialog asking you
  226. to close open files.
  227.  
  228. * Other useful commands
  229.  
  230. It's always a good idea to diff files you are about to check in, to
  231. make sure that you know what is going into the repository. MacCVS Pro
  232. has two commands to do this: Status:Diff, which shows UNIX-style
  233. diff output, and Status:Compare with original, which shows a more
  234. useful view of the source using colors to hilight new, changed and
  235. removed lines.
  236.  
  237. To add a new file or folder to the repository, use the Action:Add menu
  238. command. Added files automatically get the checkin comment "First checked
  239. in". Be careful when adding new files to choose the right file type;
  240. source files should be added as TEXT, resource files as AppleSingle, and
  241. other files (e.g. GIF files, SIT archives) as binary. Some attempt is made
  242. to set the default to the correct one.
  243.  
  244. * Interoperability with other CVS clients
  245.  
  246. Due to the different way in which MacCVS Pro stores revision and other
  247. information, source trees checked out using MacCVS Pro cannot be safely
  248. used with other Macintosh CVS clients, and vice versa. You should stick
  249. to using a single client on your source tree. This additional information
  250. permits increased functionality and optimization in our client, so we
  251. believe this to be worthwhile.
  252.  
  253. Known bugs & Limitations
  254. ------------------------
  255.  
  256. We know of no crashing bugs in MacCVS Pro.
  257.  
  258. The UI still needs some fine-tuning, and could do with a little more
  259. functionality in project views (e.g. resizing columns). There are some
  260. minor refresh problems here too.
  261.  
  262. * Other known bugs:
  263.     Pressing the "Stop" button while decoding an AppleSingle file will bring
  264.     up an "Error 700" message in the message window. This is harmless.
  265.     
  266.     If you select thousands of items, MacCVS will slow down to a halt.
  267.     
  268.     There is a bug in Find Lurkers where it won't find some modified files.
  269.     This only happens if you're running a Find Lurkers operation on
  270.     directory that already has some CVS operation (ie. checkout/update)
  271.     running on it. I don't know what the deal is here yet.
  272.     
  273.     If you open a non-modified, non-MROed, file with Resourcer 2.0 it will
  274.     ask you if you want to open the file read only. If you choose the modify
  275.     the file, Resourcer will update the ckid with a bad checksum. Simply
  276.     open the 'ckid' resource, type in 0 for the checksum, close the resource
  277.     and save the file. That should clear up the problem. This bug is fixed
  278.     in Resorcerer 2.2.
  279.     
  280.     Trying to commit a file that actually hasn't changed will fail. However,
  281.     the CVS server never sends an error message so you never get any
  282.     feedback that your operation has failed.
  283.     
  284.     The project views do not update folder tags and other attributes if the
  285.     folder is collapsed.
  286.     
  287.     Drag selecting any of the TE fields sometimes does weird things. This is
  288.     not a bug in MacCVS, but a problem in the PowerPlant LTextEditView
  289.     class.
  290.     
  291.     Due to the poorly specified cvs server protocol, there are some problems
  292.     with operations on files in the root directory, and when using alias
  293.     directories (server-side aliases, that is).
  294.  
  295. * Limitations
  296.     
  297.     Won't work with really old CVS servers (pre 1.5)
  298.     
  299.     Trees checked out with MacCVS Pro can't be used with other Macintosh
  300.     CVS clients.
  301.     
  302.     File names > 29 chars cause an error (This is a limitation of the Mac
  303.     file system and is not a MacCVS bug. Such files are simply ignored,
  304.     and do not interrupt the checkout process.)
  305.     
  306.     No command line, not all CVS client operations supported (at present).
  307.     
  308.     No gzip support (i.e. the equivalent of cvs -z9 checkout is not available).
  309.  
  310. Version history
  311. ---------------
  312.  
  313. 2.2.1    January 1999
  314.  
  315. Updated to the new PowerPlant with Appearance Manager support, and
  316. CodeWarrior Pro 4.
  317. Support for Kerberos authentication added
  318. Fixes for some cosmetic bugs.
  319. Fixed a bug with aliased directories (CVS directory aliases, that is)
  320.  
  321. 2.1b2    12 May 1998
  322.  
  323. Fixed a problem with Find Lurkers, which caused new files without resource
  324. forks not to show up in the lurkers list.
  325.  
  326. Fixed a problem when committing files using keywords, which caused the
  327. file not to be updated in your local tree.
  328.  
  329. Some minor window layout tweaks.
  330.  
  331.  
  332. 2.1b1    30 April 1998
  333.  
  334. First public release.
  335.  
  336.  
  337.  
  338. Last modified 99/01/12
  339. Simon Fraser sfraser@netscape.com
  340.  
  341.